home *** CD-ROM | disk | FTP | other *** search
/ The Mac Mega CD - Killer Software / The Mac Mega CD - Killer Software (May 1996).dmg / Shareware City / Sound / MacMikMod 2.10+src / docs / mdriver.doc < prev    next >
Encoding:
Text File  |  1995-11-19  |  10.6 KB  |  404 lines  |  [TEXT/CWIE]
  1. ⁄ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒø
  2. ≥MDRIVER.C Module Documentation≥
  3. ¿ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒŸ
  4.  
  5. Date last modified: October 20, 1995
  6.  
  7. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  8.  
  9. General information:
  10.  
  11. As far as the other modules are concerned, the driver module is a set of 
  12. _universal_ routines for producing sound. The other modules don't have to 
  13. worry about how to drive a particular soundcard, they just 'ask' the driver 
  14. module to reserve so many voices, to mix at a certain rate and to play a 
  15. voice every once in a while. The driver module will adjust the requested 
  16. mixing mode and frequency if the actual soundcard doesn't support it.
  17.  
  18. When we take a closer look at the driver module we see that it's just a set 
  19. of 'glue' functions that redirect the driver function calls to the actual 
  20. selected soundcard driver:    
  21.  
  22.  
  23.         ⁄ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒ¬ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒø
  24.         ≥DRIVER BLACKBOX≥                        ≥
  25.         √ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒŸ                        ≥
  26.         ≥                                        ≥
  27.      sb     ≥⁄ƒƒƒƒƒƒƒƒƒƒø                            ≥
  28.    hardwareƒ≈¥sb driver √ÕÕª <- selected driver      ≥
  29.         ≥¿ƒƒƒƒƒƒƒƒƒƒŸ  ∫                         ≥
  30.         ≥              ∫                         ≥
  31.      gus    ≥⁄ƒƒƒƒƒƒƒƒƒƒø  ∫                         ≥
  32.    hardwareƒ≈¥gus driver√ƒƒ∫                         ≥
  33.         ≥¿ƒƒƒƒƒƒƒƒƒƒŸ  ∫ ⁄ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒø ≥
  34.         ≥              »Õ¥DRIVER GLUE FUNCTIONS√ƒ≈<>ƒ interface to
  35.      pas    ≥⁄ƒƒƒƒƒƒƒƒƒƒø  ≥ ¿ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒŸ ≥    other modules
  36.    hardwareƒ≈¥pas driver√ƒƒ¥                         ≥
  37.         ≥¿ƒƒƒƒƒƒƒƒƒƒŸ  ≥  - common driver        ≥
  38.         ≥              ≥    routines             ≥
  39.      other  ≥⁄ƒƒƒƒƒƒƒƒƒƒø  ≥                         ≥
  40.    hardwareƒ≈¥etc..     √ƒƒŸ  - common driver        ≥
  41.         ≥¿ƒƒƒƒƒƒƒƒƒƒŸ       variables            ≥
  42.         ≥                                        ≥
  43.         ¿ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒŸ
  44.  
  45. To prevent having to link _all_ lowlevel soundcard drivers to the player 
  46. (when you only want to use the gus-driver), the first thing the main module 
  47. has to do before using the driver module is to 'register' all drivers it 
  48. might need. This way only the registered drivers will get linked to the 
  49. executable, thus reducing the size of it. So registering a driver to the 
  50. driver module is a way of saying 'lookee here, another driver you can choose
  51. from'.
  52.  
  53. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  54.  
  55. MDRIVER public variables:
  56.  
  57. DRIVER *md_driver       // pointer to the currently used driver
  58.             // this variable is set after a call to MD_Init()
  59.  
  60. UWORD  md_device        // device-number
  61. UWORD  md_mixfreq       // current mixing frequency
  62. UWORD  md_dmabufsize    // dma buffer size (for sb)
  63. UWORD  md_mode          // output mode
  64. UBYTE  md_numchn        // number of channels to use
  65. UBYTE  md_bpm           // current driver BPM speed
  66.  
  67. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  68.  
  69. void MD_InfoDriver(void)
  70. ========================
  71.  
  72. Input parms:
  73.  
  74.     -
  75.  
  76.  
  77. Returns:
  78.  
  79.     -
  80.  
  81.  
  82. Description:
  83.  
  84. This function produces a list of all registered drivers to stdout. Use it 
  85. _after_ you've registered all drivers using ML_RegisterDriver().
  86.  
  87. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  88.  
  89. void MD_RegisterDriver(DRIVER *drv)
  90. ===================================
  91.  
  92. Input parms:
  93.  
  94.     drv     pointer to a DRIVER structure
  95.  
  96.  
  97. Returns:
  98.  
  99.     -
  100.  
  101.  
  102. Description:
  103.  
  104. Before you can use any of the other device-routines you first have to 
  105. register the drivers you want to use. This way only the registered drivers 
  106. are linked to the resulting program, so if you only want to support a single 
  107. soundcard your program won't be so big.
  108.  
  109.  
  110. Example:
  111.  
  112.     [ at the start of the main program: ]
  113.  
  114.     {
  115.         ...
  116.  
  117.                 MD_RegisterDriver(&drv_gus);
  118.                 MD_RegisterDriver(&drv_sb);
  119.  
  120.         MD_InfoDriver();
  121.         ...
  122.         ...
  123.  
  124.     }
  125.  
  126. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  127.  
  128. void MD_RegisterPlayer(void (*player)(void))
  129. ============================================
  130.  
  131. Input parms:
  132.  
  133.         player  pointer to a player routine which has to be called at
  134.                 BPM rate.
  135.  
  136. Returns:
  137.  
  138.     -
  139.  
  140.  
  141. Description:
  142.  
  143. Sets the routine that will be called by the driver to update the voices, and
  144. play the music. If you're using soundblaster and you have a large DMA buffer
  145. this playroutine will be called in bursts.
  146.  
  147. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  148.  
  149. BOOL MD_Init(void)
  150. ==================
  151.  
  152. Input parms:
  153.  
  154.     -
  155.  
  156. Returns:
  157.  
  158.     True if soundcard init succeeded, FALSE otherwise.
  159.  
  160. Description:
  161.  
  162. Before calling this routine you have to initialize some variables:
  163.  
  164.     md_mixfreq:     What mixing frequency do you want to use (Hz)
  165.  
  166.     md_dmabufsize:  How big the soundcard dma-buffer should be (in bytes)
  167.  
  168.     md_mode:        Flags what output mode to use.. Use the bitwise OR (|)
  169.             to combine flags:
  170.             
  171.             DMODE_16BITS : 16 bits output
  172.             DMODE_STEREO : stereo output
  173.                         DMODE_INTERP : interpolated mixing
  174.  
  175.     md_device:      The number of the driver you want to use. Use 0 to
  176.             use the first soundcard it detects.
  177.  
  178. MD_Init will call the initialisation routine of the specified driver. When 
  179. the soundcard doesn't support any of selected mixing modes or mixing 
  180. frequency it will adjust the md_mode & md_mixfreq to values that _are_ 
  181. supported. For example, if you have a SB-pro and you try to init it with the 
  182. DMODE_16BITS flag set, it removes this flag after the MD_Init() call.
  183.  
  184. !!! It is ILLEGAL to change the variables md_mixfreq,md_dmabufsize, md_mode & 
  185. md_device AFTER you've called MD_Init()!!!
  186.  
  187. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  188.  
  189. **** The following routines may only be called if MD_Init succeeded ****
  190.  
  191. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  192.  
  193. void MD_Exit(void)
  194. ==================
  195.  
  196. Input parms:
  197.  
  198.     -
  199.  
  200. Returns:
  201.  
  202.     -
  203.  
  204. Description:
  205.  
  206. De-initialises the soundcard after you're done with it.
  207.  
  208. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  209.  
  210. SWORD MD_SampleLoad(FILE *fp,ULONG size,ULONG reppos,ULONG repend,UWORD flags)
  211. ==============================================================================
  212.  
  213. Input parms:
  214.  
  215.     fp      filepointer to raw sample data
  216.     size    size of the sample (in samples!)
  217.     reppos  repeat start offset
  218.     repend  repeat end offset
  219.     flags   flags which indicate the format of the sample
  220.  
  221. Returns:
  222.  
  223.     A handle which identifies the sample, or -1 incase of an error
  224.  
  225. Description:
  226.  
  227. Loads a raw sample from file to the soundcard. It returns a number (handle)
  228. which identifies the sample (you need the handle if you want to play the sample).
  229.  
  230. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  231.  
  232. void MD_SampleUnLoad(SWORD handle)
  233. ==================================
  234.  
  235. Input parms:
  236.  
  237.     handle  the handle that identifies the sample to be unloaded.
  238.  
  239. Returns:
  240.  
  241.     -
  242.  
  243. Description:
  244.  
  245. Frees the sample which was previously loaded using MP_SampleLoad().
  246.  
  247. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  248.  
  249. void MD_PlayStart(void)
  250. =======================
  251.  
  252. Input parms:
  253.  
  254.     -
  255.  
  256. Returns:
  257.  
  258.     -
  259.  
  260. Description:
  261.  
  262. Starts the mixing process of the soundcard (after calling this routine you 
  263. can use the MD_Voice* routines to make noise). Before calling this routine 
  264. you have to set the variable 'md_numchn' so it knows how many channels it has 
  265. to mix. You can call MP_Update() after this routine to do the actual updating
  266. of voices.
  267.  
  268. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  269.  
  270. void MD_PlayStop(void)
  271. ======================
  272.  
  273. Input parms:
  274.  
  275.     -
  276.  
  277. Returns:
  278.  
  279.     -
  280.  
  281. Description:
  282.  
  283. Stops soundcard output. 
  284.  
  285. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  286.  
  287. void MD_VoiceSetVolume(UBYTE voice,UBYTE vol)
  288. =============================================
  289.  
  290. Input parms:
  291.  
  292.     voice   which voice to change the volume for.
  293.     vol     new volume setting for this voice (0-64)
  294.  
  295. Returns:
  296.  
  297.     -
  298.  
  299. Description:
  300.  
  301. Sets the volume of a single voice. Note that it doesn't change the volume 
  302. immediately but at the next MD_Update() call (this is true for all MD_Voice* 
  303. routines).
  304.  
  305. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  306.  
  307. void MD_VoiceSetFrequency(UBYTE voice,ULONG frq)
  308. ================================================
  309.  
  310. Input parms:
  311.  
  312.     voice   which voice to change the frequency.
  313.     frq     new playback frequency this voice.
  314.  
  315. Returns:
  316.  
  317.     -
  318.  
  319. Description:
  320.  
  321. Sets the playback frequency of a single voice.
  322.  
  323. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  324.  
  325. void MD_VoiceSetPanning(UBYTE voice,UBYTE pan)
  326. ==============================================
  327.  
  328. Input parms:
  329.  
  330.     voice   which voice to change the panning position.
  331.     pan     new panpos for this voice.
  332.  
  333. Returns:
  334.  
  335.     -
  336.  
  337. Description:
  338.  
  339. Changes the panning position (=balance) for this voice. 0 is all left, 255 is 
  340. all right.
  341.  
  342. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  343.  
  344. void MD_VoicePlay(UBYTE voice,
  345.                   SWORD handle,
  346.           ULONG start,ULONG size,
  347.           ULONG reppos,ULONG repend,
  348.           UWORD flags)
  349. ============================================
  350.  
  351. Input parms:
  352.  
  353.     voice   which voice to start playing a new sample on
  354.     handle  the handle that identifies the sample
  355.     start   the starting offset (in samples!)
  356.     size    the size of the sample (in samples!)
  357.     reppos  repeat start position offset.
  358.     repend  repeat end position offset.
  359.     flags   identifies the type of sample, and if it has to loop.
  360.  
  361. Returns:
  362.  
  363.     -
  364.  
  365. Description:
  366.  
  367. Starts playing a new sample on the specified channel, using the requested 
  368. start,size and loop parameters (using the current volume, frequency and 
  369. panning parameters of a voice).
  370.  
  371. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  372.  
  373. void MD_Update()
  374. ================
  375.  
  376. Input parms:
  377.     -
  378.  
  379. Returns:
  380.     -
  381.  
  382. Description:
  383.  
  384. Call this routine regularly to update the sound.
  385. NEW since 2.09: no need to call this at the exact BPM rate.. just call it
  386. every frame or so.
  387.  
  388. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  389.  
  390. void MD_SetBPM(UBYTE bpm)
  391. =========================
  392.  
  393. Input parms:
  394.  
  395.         bpm     New driver bpm rate
  396.  
  397. Returns:
  398.     -
  399.  
  400. Description:
  401.  
  402. Sets the BPM rate at which the playing routine is called.
  403.  
  404.